home *** CD-ROM | disk | FTP | other *** search
/ AOL File Library: 2,801 to 2,900 / aol-file-protocol-4400-2801-to-2900.zip / AOLDLs / TAWUG / TAWUG Disk No. 36 (SHK) / TAWUG.36.shk / ALU.DOC.AW (.txt) < prev    next >
AppleWorks Document  |  1986-06-27  |  13KB  |  250 lines
  1. O=====|====|====|====|====|====|====|====|====|====|====|====|====|====|====|===
  2. Applesoft Library Utility
  3. A)pplesoft
  4. L)ibrary
  5. U)tility
  6. A Users Guide
  7. -------------%
  8. copyright (C) 1986, Donald R. Elton
  9. Living Legends Software
  10. 1915 Froude St.
  11. San Diego, CA 92107
  12. (619) 222-3722 [ voice ]*
  13. (619) 281-7222 [ modem -- login: guest ]
  14. Applesoft Library Utility
  15. ALU - Applesoft Library Utility!
  16. ===============================
  17. :The ProDOS version of ALU and its UNIX, PC-DOS and MS-DOS ;
  18. 9equivalents are based upon the CP/M library utility made ?
  19. =popular by RBBS's and RCP/M systems around the world.  These ?
  20. =library utility programs are used to maintain and manipulate ?
  21. =a large data file (commonly known as an LBR file) made up of !
  22. two or more program/data files.
  23. Library Files
  24. =============
  25. =Most library files contain two or more program or data files ?
  26. =that are somehow related to one another.  By "packing" these 9
  27. 7files into one large file it makes it easier for other >
  28. <computer users to download all of the necessary modules and 9
  29. 7information without having to worry about whether they ?
  30. =missed out on a vital portion of your package.  Once the LBR ?
  31. =file is downloaded it can be "unpacked" (seperated back into >
  32. <the original files) with another LU utility and used by the ?
  33. =recipient.  The following example shows how useful a program 
  34. like ALU can be:
  35.               ABC.SHEET -----------------\-
  36.               ABC.GRAPH -----------------\\7
  37.                 ABC.A/R ------------------>> ABC.DATA-
  38.                 ABC.A/P -----------------//,
  39.                 ABC.G/L -----------------/
  40.        original files from            the resulting LU file>
  41.          The ABC Company             ready to be transmitted
  42. <The only requirement is that both the sending and receiving <
  43. :parties have a library utility program to pack/unpack the 
  44. files.
  45. :The common denominator of all LBR files is that they have >
  46. <the same structure, regardless of the operating system used :
  47. 8when the LBR file was created.  This version of ALU has ?
  48. =ProDOS-specific enhancements that are compatible with the LU =
  49. ;command found in the Extended Command Processor (ECP), and <
  50. :is upward and downward compatible with the versions of LU <
  51. used on other computers and under other operating systems.
  52. Applesoft Library Utility
  53. Using ALU
  54. =========
  55. <Since ALU allows the "packing" of many files into one large =
  56. ;file, it lends itself to manipulating multi-file programs. ?
  57. =For example, many programs may need several utility modules, >
  58. <help files and printer drivers.  Rather than have to search ;
  59. 9through an entire Data Library for all the files you can 9
  60. 7download just the necessary LBR file and "unpack" it.  =
  61. ;Packed files generated by ALU use the ProDOS file type LBR 
  62. ($20).
  63. 9Note that this version of ALU does not check the type of ?
  64. =library file before attempting to manipulate it.  Use of the ?
  65. =LBR file type is optional at present to avoid confusion with <
  66. :other ProDOS-based programs, although Apple Computer Inc. <
  67. :has reserved $20 in the ProDOS FILE_TYPE table as the LBR 
  68. file identifier.
  69. 9LBR files generated by ALU contain one or more ProDOS or <
  70. :alien files and a simple directory.  Whenever an existing =
  71. ;library is changed (if an individual file has been changed <
  72. :or deleted) the library requires "reorganizing".  More on 
  73. this later.
  74. ALU operation is quite simple.  There are only a few<
  75. commands, and each is described in the following sections.
  76. Creating An LBR File
  77. ====================
  78. 7ALU must be run from ProDOS Basic.  After starting the =
  79. program by typing "-ALU" or "BRUN ALU" the following prompt
  80. will be displayed.
  81. :You should then enter the command string in the following 9
  82. 7format, or just press the RETURN key to exit ALU.  The 8
  83. syntax for commands given to ALU follows this pattern.
  84. <library file name> <command> { <optional filenames>}
  85. Applesoft Library Utility
  86. For example:
  87. MYFILE.LBR U /PRODOS/FILE1 /PRODOS/FILE2 /PRODOS/FILE3
  88. 9would create an LBR file named MYFILE.LBR containing the ;
  89. three files FILE1, FILE2 and FILE3 from the disk /PRODOS.
  90. MYFILE.LBR T
  91. 7would list all the files contained within the LBR file 
  92. MYFILE.LBR.
  93. ALU Commands
  94. ============
  95. <All ALU commands are a single letter.  Only one command can 
  96. be entered at a time.
  97. >[A]  Unpack all files from the LBR file.  This is the same    @
  98. >     as the [E] (extract) command, followed by all the file   @
  99. >    names.  This is much easier is all you want to do is      
  100.     remove all the files.
  101. [Q]  Unpack all files in prompted mode.
  102. >[T]  List all files contained in the LBR file. Each filename  @
  103. >     is listed, along with the size of the file in            @
  104. >     hexadecimal bytes.  If this library member was added to  @
  105. >     the LBR file by the ECP version of LU or this version    @
  106. >     of ALU then the ProDOS file type will also be            
  107.      displayed.
  108. [L]  Same as [T].
  109. >[E]  Extract a file from the LBR file.  The file(s) to be     @
  110. >     extracted are entered after the LBR file name.  Each     @
  111. >     file will be extracted and copied to a disk file of the  @
  112. >     same name.  Note that only a copy of the file is         @
  113. >     extracted, the original library is unchanged by this     
  114.      command.
  115. >[U]  Update a library.  This is also used to create new       @
  116. >     libraries.  File name(s) are entered after the LBR file  @
  117. >     name, and each file is added to the library.  Any file   @
  118. >     of the same name already in the library will be deleted  @
  119. >     first, otherwise just added.  Updating a library always  @
  120. >     increases the size of the library as new members are     @
  121. >     always appended to the end of the file.  Please read     !
  122.      about reorganizing, below.
  123. Applesoft Library Utility
  124. >     If the library file does not exist (creating a new one)  ;
  125.      then the library will be created with 32 file slots.
  126. >[D]  Delete a file.  This just marks the file within the      @
  127. >     library as "deleted".  The library file will not change  @
  128. >     in size; it does not remove the data contained by the    (
  129.      file.  See reorganization, below.
  130. >[R]  Reorganizes the library.  All free space (from deleted   ?
  131. =     files, or existing files that were Updated) is freed    @
  132. >     up, and the LBR file generally becomes smaller.  Should  @
  133. >     be used after a Delete or Update command.  Creates a     @
  134. >     temporary file called ECP.LU.....TEMP, therefore you     @
  135. >     should not use this file name elsewhere.  Note that a    @
  136. >     lot of disk space is needed temporarily by this program  @
  137. >     as it basically copies all of the active members of the  @
  138. >     original LBR file into the temp file above.  If the      @
  139. >     copy is successful then the old file is deleted and the  9
  140.      temporary file is renamed as the new library file.
  141. Reorganizing LBR Files
  142. ======================
  143. :The structure of an LBR file (as described below) is very =
  144. ;simple.  Because of its simplicity, files that are deleted ?
  145. =or changed still consume space within the LBR file.  Any LBR :
  146. file must be "squeezed" whenever the library is changed.
  147. 9Deleting a file merely marks the file as "deleted" -- it =
  148. ;DOES NOT remove data contained in the LBR file; therefore, 8
  149. 6the library must be reorganized.  This results in the =
  150. ;creation of a new library, the copying of all active files 9
  151. to it, and the removal of all deleted or replaced data.
  152. <GENERAL RULE:  Reorganize after deleting a file or updating 
  153. an existing file.
  154. LBR File Structure
  155. ==================
  156. 7The LBR file contains a simple directory at the start, =
  157. ;followed by all the data contained in the file.  New files =
  158. ;are added to the end of the LBR file.  The directory entry ?
  159. =for each file points to the data and contains the length and >
  160. <other ProDOS directory information (if the member was added 5
  161. with the ECP version of LU or this version of ALU).
  162. Applesoft Library Utility
  163. Each directory entry is:
  164. 00:   file status (00 = active, FE = unused, FF = deleted)
  165. 01:   11 character filename
  166. =PLEASE NOTE that file naming and storage conventions are not ?
  167. =the same between CP/M, MS-DOS, UNIX, and ProDOS.  The former =
  168. ;three operating systems can have up to 8 characters in the ?
  169. =filename, followed by an optional 3 character arbitrary file >
  170. <extension.  A CP/M version of ALU (usually called "LU.COM") 
  171. would be stored as:
  172.      "LU______COM"   ( "_" designates a space )
  173. <The ALU program will not change this file name format in an =
  174. ;existing LBR file or in LBR files that it reorganizes.  If =
  175. ;you extract or list the members of this LBR file the above =
  176. ;file name will be displayed as "LUCOM".  Some MS-DOS files >
  177. <may start with digits; for example, "1.BAT".  This filename ;
  178. 9is invalid under ProDOS, so ALU will append a "P" to the 9
  179. 7front of the file name in an attempt to create a valid 
  180. ProDOS filename ("P1BAT").
  181. 12:   16 bit offset to start of data (in 128 byte sectors)
  182. 14:   16 bit data length             (in 128 byte sectors)
  183. ------------------------------------------------------------
  184. =NOTE that the fields that follow are NOT in the standard ALU >
  185. <specification, but are added to better support Apple ProDOS ?
  186. =files.  The presence of the following data should not affect ;
  187. 9the operation of ALU versions running on other operating 
  188. systems.
  189. >16:  ProDOS Access bits.  Upon extraction, all files will be  
  190.     UNLOCKed.
  191. 17:  ProDOS File type.)
  192. 18:  16 bit ProDOS auxiliary file type./
  193. 20:  16 bit ProDOS date of last modification./
  194. 22:  16 bit ProDOS time of last modification.%
  195. 24:  24 bit ProDOS End of File mark2
  196. 31:  16 bit value $A2A2 (for Apple 2 of course!)
  197. =This tells ALU that the file contains valid ProDOS directory 
  198. information in bytes 16-32.
  199. Applesoft Library Utility
  200. ------------------------------------------------------------
  201. :Since the original program was written in BDS C, all file >
  202. <offsets and lengths are in multiples of 128 bytes (the CP/M =
  203. ;"sector size").  ALU multiplies these values by 128 before ;
  204. 9using.  All file sizes are rounded up to the nearest 128 
  205. bytes.
  206. 5The offset is the location of the data for the file, (
  207. relative to the start of the LBR file.
  208. 8The first directory entry is the directory itself.  The <
  209. :filename is always blank, the offset is not used, and the (
  210. length is the length of the directory.
  211. Peculiarities
  212. =============
  213. <A side effect of the original design: all files are rounded >
  214. <up to the nearest 128 bytes.  This does not matter for most >
  215. <files, but some files -- a spreadsheet, for example -- will =
  216. ;not work unless the size is exactly right.  Files added to :
  217. the LBR file by ALU will not have this problem since ALU8
  218. 6keeps up with the programs' correct EOF (end of file) 
  219. position.
  220. =If you're using ALU to archive files it's a good idea to use ?
  221. =the SQ utility (under development for ProDOS ECP) to squeeze >
  222. <the files before placing them in a library file.  Squeezing ?
  223. =a LBR file can be done, but may not be reliable.  Best to SQ 
  224. first, then run ALU.
  225. ;An additional note:  due to the methods used by CompuServe 6
  226. 4to store files, none of the LBR files in their Data :
  227. 8Libraries are squeezed.  This seems to be unique to CIS <
  228. :only, and does not necessarily apply to files on bulletin 
  229. board systems.
  230. Further Information
  231. ===================
  232. 8ALU is distributed as a Public Domain program by Living <
  233. :Legends Software.  We strongly encourage our fellow Apple >
  234. <users to spread this program around to their friends and to ?
  235. =other BBS systems so that others can enjoy the benifits that =
  236. ;come from combining numerous files into one large, easy to 
  237. handle LBR file.
  238. Applesoft Library Utility
  239. =Questions regarding ALU can be forwarded to us in San Diego, 
  240. or you can leave E-mail on:
  241. CompuServe      75746,2550
  242. Delphi          LIVLEG
  243. BIX             jerryh)
  244. ARPA            !bang!crash!jerryh@nosc 
  245. ProLine [sol]   jerryh, delton
  246. Formatted for Appleworks by Bill Cronister, 
  247. The AppleWorks Users Group,
  248. P.O. Box 24869
  249. Denver, CO  80224-0869
  250.